home *** CD-ROM | disk | FTP | other *** search
/ Aminet 15 / Aminet 15 - Nov 1996.iso / Aminet / dev / gcc / ixemsdk.lha / man / cat3 / time2posix.0 < prev    next >
Text File  |  1996-09-02  |  4KB  |  133 lines
  1.  
  2.  
  3.  
  4. TIME2POSIX(3)                                       TIME2POSIX(3)
  5.  
  6.  
  7. NNAAMMEE
  8.        time2posix, posix2time - convert seconds since the Epoch
  9.  
  10. SSYYNNOOPPSSIISS
  11.        ##iinncclluuddee <<ssyyss//ttyyppeess..hh>>
  12.        ##iinncclluuddee <<ttiimmee..hh>>
  13.  
  14.        ttiimmee__tt ttiimmee22ppoossiixx((tt))
  15.        ttiimmee__tt tt
  16.  
  17.        ttiimmee__tt ppoossiixx22ttiimmee((tt))
  18.        ttiimmee__tt tt
  19.  
  20.        cccc ...... --llzz
  21.  
  22. DDEESSCCRRIIPPTTIIOONN
  23.        IEEE  Standard  1003.1  (POSIX)  legislates  that a time_t
  24.        value  of  536457599  shall  correspond  to  "Wed  Dec  31
  25.        23:59:59  GMT  1986."  This effectively implies that POSIX
  26.        time_t's cannot include leap seconds and, therefore,  that
  27.        the system time must be adjusted as each leap occurs.
  28.  
  29.        If the time package is configured with leap-second support
  30.        enabled, however, no such adjustment is needed and  time_t
  31.        values  continue  to  increase over leap events (as a true
  32.        `seconds since...' value).  This means that  these  values
  33.        will differ from those required by POSIX by the net number
  34.        of leap seconds inserted since the Epoch.
  35.  
  36.        Typically this is not a problem  as  the  type  time_t  is
  37.        intended  to be (mostly) opaque--time_t values should only
  38.        be obtained-from and passed-to functions such as  _t_i_m_e_(_2_),
  39.        _l_o_c_a_l_t_i_m_e_(_3_),  _m_k_t_i_m_e_(_3_), and _d_i_f_f_t_i_m_e_(_3_).  However, POSIX
  40.        gives an arithmetic expression for  directly  computing  a
  41.        time_t  value  from  a given date/time, and the same rela-
  42.        tionship is assumed by some (usually older)  applications.
  43.        Any  programs  creating/dissecting  time_t's  using such a
  44.        relationship will typically not handle intervals over leap
  45.        seconds correctly.
  46.  
  47.        The  _t_i_m_e_2_p_o_s_i_x  and  _p_o_s_i_x_2_t_i_m_e functions are provided to
  48.        address this time_t mismatch by converting  between  local
  49.        time_t  values  and their POSIX equivalents.  This is done
  50.        by accounting for the number  of  time-base  changes  that
  51.        would  have  taken place on a POSIX system as leap seconds
  52.        were inserted or deleted.  These converted values can then
  53.        be  used  in lieu of correcting the older applications, or
  54.        when communicating with POSIX-compliant systems.
  55.  
  56.        _T_i_m_e_2_p_o_s_i_x is single-valued.  That is, every local  time_t
  57.        corresponds  to a single POSIX time_t.  _P_o_s_i_x_2_t_i_m_e is less
  58.        well-behaved: for a positive leap second hit the result is
  59.        not  unique, and for a negative leap second hit the corre-
  60.        sponding POSIX time_t doesn't exist so an  adjacent  value
  61.  
  62.  
  63.  
  64.                                                                 1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. TIME2POSIX(3)                                       TIME2POSIX(3)
  71.  
  72.  
  73.        is  returned.   Both  of  these are good indicators of the
  74.        inferiority of the POSIX representation.
  75.  
  76.        The following table summarizes the relationship between  a
  77.        time  T  and  it's conversion to, and back from, the POSIX
  78.        representation over the leap second inserted at the end of
  79.        June, 1993.
  80.        DATE     TIME     T   X=time2posix(T) posix2time(X)
  81.        93/06/30 23:59:59 A+0 B+0             A+0
  82.        93/06/30 23:59:60 A+1 B+1             A+1 or A+2
  83.        93/07/01 00:00:00 A+2 B+1             A+1 or A+2
  84.        93/07/01 00:00:01 A+3 B+2             A+3
  85.  
  86.        A leap second deletion would look like...
  87.  
  88.        DATE     TIME     T   X=time2posix(T) posix2time(X)
  89.        ??/06/30 23:59:58 A+0 B+0             A+0
  90.        ??/07/01 00:00:00 A+1 B+2             A+1
  91.        ??/07/01 00:00:01 A+2 B+3             A+2
  92.  
  93.                       [Note: posix2time(B+1) => A+0 or A+1]
  94.  
  95.        If  leap-second support is not enabled, local time_t's and
  96.        POSIX time_t's are equivalent,  and  both  _t_i_m_e_2_p_o_s_i_x  and
  97.        _p_o_s_i_x_2_t_i_m_e degenerate to the identity function.
  98.  
  99. SSEEEE AALLSSOO
  100.        difftime(3), localtime(3), mktime(3), time(2)
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.                                                                 2
  131.  
  132.  
  133.